13.3 MCP 身份验证

MCP 支持多种身份验证方式，确保安全地连接到 MCP 服务器。

OAuth 2.0#

OAuth 2.0 流程#

MCP 服务器可以使用 OAuth 2.0 进行身份验证：

1. Claude Code 发起 OAuth 请求
2. 用户重定向到授权页面
3. 用户授权应用
4. 授权服务器返回访问令牌
5. Claude Code 使用令牌访问 MCP 服务器

配置 OAuth 2.0#

添加 OAuth 服务器

bash
复制
# 添加需要 OAuth 的服务器
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

进行身份验证

bash
复制
# 在 Claude Code 中进行身份验证
/mcp
# 选择需要身份验证的服务器
# 选择 "github"

OAuth 流程

bash
复制
# 1. Claude Code 显示授权 URL
# 请访问以下 URL 进行授权：
# https://github.com/login/oauth/authorize?client_id=...

# 2. 用户访问 URL 并授权
# 3. 授权服务器返回访问令牌
# 4. Claude Code 保存令牌

OAuth 2.0 作用域#

定义作用域

OAuth 2.0 使用作用域限制权限：

bash
复制
# 添加带作用域的服务器
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
--scope "repo,user"

常见作用域

• repo: 仓库访问权限
• user: 用户信息访问权限
• admin: 管理员权限
• read: 只读权限
• write: 读写权限

令牌管理#

查看令牌

bash
复制
# 查看已保存的令牌
显示 OAuth 令牌

刷新令牌

bash
复制
# 刷新访问令牌
刷新 GitHub 令牌

撤销令牌

bash
复制
# 撤销访问令牌
撤销 GitHub 令牌

API 密钥#

使用 API 密钥#

添加带 API 密钥的服务器

bash
复制
# Bearer 令牌
claude mcp add --transport http api https://api.example.com/mcp \
--header "Authorization: Bearer your-api-key"

# API 密钥
claude mcp add --transport http api https://api.example.com/mcp \
--header "X-API-Key: your-api-key"

# 自定义标头
claude mcp add --transport http api https://api.example.com/mcp \
--header "X-Custom-Auth: your-custom-key"

环境变量

使用环境变量传递 API 密钥：

bash
复制
# 设置环境变量
export API_KEY="your-api-key"

# 使用环境变量
claude mcp add --transport http api https://api.example.com/mcp \
  --header "Authorization: Bearer ${API_KEY}"

密钥安全#

加密存储

Claude Code 加密存储 API 密钥：

bash
复制
# 密钥自动加密存储
claude mcp add --transport http api https://api.example.com/mcp \
--header "Authorization: Bearer your-api-key"

密钥轮换

定期轮换 API 密钥：

bash
复制
# 1. 生成新密钥
# 2. 更新服务器配置
claude mcp remove api
claude mcp add --transport http api https://api.example.com/mcp \
  --header "Authorization: Bearer new-api-key"

# 3. 撤销旧密钥

证书身份验证#

使用证书#

添加带证书的服务器

bash
复制
# 使用客户端证书
claude mcp add --transport http secure-api https://api.example.com/mcp \
--cert /path/to/cert.pem \
--key /path/to/key.pem

# 使用 CA 证书
claude mcp add --transport http secure-api https://api.example.com/mcp \
--cacert /path/to/ca.pem

证书格式

支持的证书格式：

• PEM: 最常用的格式
• DER: 二进制格式
• PKCS12: 包含私钥和证书

证书管理#

查看证书

bash
复制
# 查看证书信息
openssl x509 -in /path/to/cert.pem -text -noout

验证证书

bash
复制
# 验证证书
openssl verify -CAfile /path/to/ca.pem /path/to/cert.pem

更新证书

bash
复制
# 1. 获取新证书
# 2. 更新服务器配置
claude mcp remove secure-api
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --cert /path/to/new-cert.pem \
  --key /path/to/new-key.pem

自定义身份验证#

自定义认证头#

bash
复制
# 使用自定义认证头
claude mcp add --transport http custom-api https://api.example.com/mcp \
--header "X-Custom-Auth: custom-value"

多因素认证#

bash
复制
# 使用多因素认证
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "X-Auth-Token: token" \
  --header "X-Auth-Code: code"

签名请求#

bash
复制
# 使用签名请求
claude mcp add --transport http signed-api https://api.example.com/mcp \
--header "X-Signature: signature" \
--header "X-Timestamp: timestamp"

身份验证最佳实践#

1. 使用最小权限原则#

bash
复制
# 只请求必要的权限
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --scope "repo:read"

2. 定期轮换凭证#

bash
复制
# 每 90 天轮换一次 API 密钥
# 设置提醒

3. 使用环境变量#

bash
复制
# 使用环境变量存储敏感信息
export API_KEY="your-api-key"
claude mcp add --transport http api https://api.example.com/mcp \
  --header "Authorization: Bearer ${API_KEY}"

4. 加密存储#

bash
复制
# 使用加密存储
# Claude Code 自动加密存储敏感信息

5. 审计访问#

bash
复制
# 定期审计访问日志
显示身份验证日志

故障排除#

OAuth 2.0 问题#

授权失败

问题: OAuth 授权失败

解决方案:

bash
复制
# 1. 检查授权 URL
/mcp

# 2. 确认用户授权
# 确保用户完成了授权流程

# 3. 检查作用域
# 确认请求的作用域正确

# 4. 重新授权
撤销 GitHub 令牌
/mcp
# 重新进行授权

令牌过期

问题: 访问令牌过期

解决方案:

bash
复制
# 1. 刷新令牌
刷新 GitHub 令牌

# 2. 如果刷新失败，重新授权
撤销 GitHub 令牌
/mcp
# 重新进行授权

API 密钥问题#

密钥无效

问题: API 密钥无效

解决方案:

bash
复制
# 1. 验证密钥
# 检查密钥是否正确

# 2. 检查密钥权限
# 确认密钥有足够的权限

# 3. 更新密钥
claude mcp remove api
claude mcp add --transport http api https://api.example.com/mcp \
--header "Authorization: Bearer new-api-key"

密钥过期

问题: API 密钥过期

解决方案:

bash
复制
# 1. 生成新密钥
# 2. 更新服务器配置
claude mcp remove api
claude mcp add --transport http api https://api.example.com/mcp \
  --header "Authorization: Bearer new-api-key"

证书问题#

证书无效

问题: 证书无效

解决方案:

bash
复制
# 1. 验证证书
openssl verify -CAfile /path/to/ca.pem /path/to/cert.pem

# 2. 检查证书有效期
openssl x509 -in /path/to/cert.pem -text -noout | grep "Not After"

# 3. 更新证书
claude mcp remove secure-api
claude mcp add --transport http secure-api https://api.example.com/mcp \
--cert /path/to/new-cert.pem \
--key /path/to/new-key.pem

证书过期

问题: 证书过期

解决方案:

bash
复制
# 1. 获取新证书
# 2. 更新服务器配置
claude mcp remove secure-api
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --cert /path/to/new-cert.pem \
  --key /path/to/new-key.pem

安全建议#

1. 保护凭证#

bash
复制
# 不要在代码中硬编码凭证
# 使用环境变量
export API_KEY="your-api-key"

# 不要在版本控制中提交凭证
# 添加到 .gitignore
echo ".env" >> .gitignore

2. 使用强凭证#

bash
复制
# 使用强密码
# 使用长随机字符串作为 API 密钥
# 定期轮换凭证

3. 限制权限#

bash
复制
# 使用最小权限原则
# 只授予必要的权限
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
--scope "repo:read"

4. 监控使用#

bash
复制
# 定期监控 API 使用
显示 API 使用统计

# 检查异常活动
显示异常访问日志

5. 及时撤销#

bash
复制
# 及时撤销不需要的凭证
撤销 GitHub 令牌
撤销 API 密钥